The routines in this file allow you to easily add a stats area to your game. You do this by creating a SpriteWorld for your stats area, then using the routines in this file to create "number Sprites" that display the numbers of the various items in your stats area, such as the current level, number of lives left, score, or any other item that needs a number. Since these are real Sprites that you are adding, you can add number Sprites to your main animation window if you wish; they don't have to be in a separate SpriteWorld.
The routines work by creating a normal Sprite with an extended Sprite record. This extended record contains the number that will be displayed when the Sprite is drawn, as well as other information about how to display the number, such as whether it is left or right justified, how many digits are in the number, etc. Additionally, the Sprite is given a special DrawProc that draws the number whenever the Sprite is drawn. This means you should not change the Sprite's DrawProc yourself, but otherwise can treat any Sprite created by these routines as a normal Sprite, adding it to any layer you wish, and even installing MoveProcs to move it around if you want.
To use SWStats.c, just add it and SWGameUtils.c to your project, and #include SWStats.h in your source files.
Getting Started
The steps for creating the stats area:
1) Create the SpriteWorld that will contain the stats Sprites, as well as any layers needed for the stats, add them to the SpriteWorld, and lock it.
2) Load the master copies of any Sprites containing the numbers you'll be using and lock them. The Sprites should contain 10 frames, starting with digit 0 and ending with digit 9. All frames should be the same height and width.
3) Call CreateStatsSpriteClone for each stats number you want to add to the animation.
4) Call SetUpStatsSprite for each stats Sprite clone you create.
5) Call SWUpdateSpriteWorld, as well as SWProcessSpriteWorld and SWAnimateSpriteWorld for the stats SpriteWorld each frame, just as you would any normal SpriteWorld.
6) Whenever you want to change the number of one of the stats Sprites, simply call SetStatsSpriteNumber.
Function Reference
CreateStatsSpriteClone
SpritePtr CreateStatsSpriteClone(
SpritePtr masterSpriteP,
short numDigits,
JustifyType justification,
Boolean fillWithZeros)
Use this function to create a clone of a master Sprite you loaded previously that contains the digits that will be used to display the Sprite's number. This clone, not the master, should be added to the animation. You can clone the same master Sprite as much as you want.
The numDigits parameter specifies how many digits to display. When the number is right-justified, the number of digits affects the position of the number; the more digits, the farther to the right the number is displayed. The justification parameter should be either kLeftJustify or kRightJustify, depending on the type of justification you want.
The fillWithZeros option only affects right-justified numbers. If true, a six-digit 1 would be displayed as 00001.
If this function fails to create the new Sprite, it returns NULL. You should always check the returned SpritePtr to make sure it's not NULL.
After calling this function, you should either call SetUpStatsSprite, or you should call SWAddSprite, SWSetSpriteLocation, SetStatsSpriteDrawProc, and SetStatsSpriteNumber to prepare the new Sprite for animation.
SetUpStatsSprite
OSErr SetUpStatsSprite(
SpritePtr statsSpriteP,
SpriteLayerP dstSpriteLayer,
DrawProcPtr drawProcP,
short horizLoc,
short vertLoc,
long theNum)
This is a "convenience" function that simply calls SWAddSprite, SWSetSpriteLocation, SetStatsSpriteDrawProc, and SetStatsSpriteNumber for you. It also checks to make sure the SpritePtr passed to this function is not NULL. If it is null, this function return s -1 as the error code. That way, you can call this function immediately after calling CreateStatsSpriteClone without having to check to make sure the SpritePtr returned by that function is not NULL first. However, you still need to check the error code returned by this function to make sure it equals noErr.
For the parameters, simply pass the SpriteLayer you want the Sprite added to, the drawProc you want this Sprite to have, as well as its starting location, and its initial number. Pass -1 as theNum if you want it to be invisible until a new number is assigned to it.
If you don't want to call this function, you must call SWAddSprite and SWSetSpriteLocation yourself. SetStatsSpriteDrawProc is optional; by default, the Sprite's drawProc is SWStdWorldDrawProc. SetStatsSpriteNumber is also optional; if you animate the SpriteWorld before giving the Sprite a number, it will be invisible.
DrawPictInFrame
OSErr DrawPictInFrame(
FramePtr dstFrameP,
short pictResID)
This is a useful utility function that loads a picture from a resource, centers it in dstFrameP, and draws it in that Frame. This is handy if you have a separate stats area that has a background pict. Simply create your SpriteWorld, lock it, and call this function, passing the spriteWorldP->backFrameP as the dstFrameP parameter, and your picture will be drawn, creating the Frame's background.
SetStatsSpriteDrawProc
void SetStatsSpriteDrawProc(
SpritePtr srcSpriteP,
DrawProcPtr drawProc)
Use this function to set the DrawProc uses to draw the digits of a stats Sprite.
IMPORTANT: Make sure not to confuse this function with SWSetSpriteDrawProc; they are NOT the same! If you call SWSetSpriteDrawProc to change a stats Sprite's drawProc, its number will no longer be drawn correctly, since a special DrawProc is installed in the Sprite when you create it with CreateStatsSpriteClone that draws the digits. This special DrawProc then calls the drawProc you pass to this function to draw each individual digit. If you called SWSetSpriteDrawProc by accident instead of SetStatsSpriteDrawProc, you'll know it when you run the program, since the number will not change no matter how much you call SetStatsSpriteNumber, and will either be 0, or will be numbers like 01, 012, 0123, etc.
When a stats Sprite is first created using CreateStatsSpriteClone, its default DrawProc is the SWStdWorldDrawProc. You can change this with either SetStatsSpriteDrawProc, or by setting up the stats Sprite with SetUpStatsSprite.
SetStatsSpriteNumber
void SetStatsSpriteNumber(
SpritePtr srcSpriteP,
long newNumber)
Call this function to change the number that is displayed by a stats Sprite. You can call this function many times per frame without a performance hit, since this only updates the number and marks the Sprite to be redrawn. The Sprite isn't actually redrawn until you process and animate the SpriteWorld.
Passing any negative number as the newNumber parameter will make the number invisible. However, if you wish to make the number more invisible, a more efficient way is to call SWSetSpriteVisible.
If the newNumber is the same as the old number the Sprite was currently displaying, this function will do nothing. This means you can call this function even if you're not sure the number has been changed without worrying that you may be causing the Sprite to be redrawn needlessly, since the Sprite will only be redrawn when the number changes.
GetStatsSpriteNumber
long GetStatsSpriteNumber(
SpritePtr srcSpriteP)
Use this function if you want to read the current value of the stats Sprite's number. Normally, you wouldn't need to do this, since you'd store your number of lives, level, score, etc. in global variables, and change those global variables directly, and then call SetStatsSpriteNumber once per frame, passing them the current values for each stats item that is stored in your global variables.
